Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/lisp/kcl/kcl.lha/doc/kclunix

Text File | 1986-06-28 | 22KB | 537 lines

            Note on KCL/UNIX

This note is intended to be read by the users of KCL/UNIX, particularly
of KCL/SUN and KCL/VAX.  It describes some problems of KCL/UNIX and how
to avoid them by using the KCL/UNIX-specific features.


* Core Dump

We can consider several situations in which KCL dumps core on UNIX.

1. The KCL compiler, by default, produces efficient but very
dangerous code.  The code seldom detects erroneous situations
such as extracting the car of a fixnum, which, in bad cases,
cause "Segmentation violation" or "Bus error" on UNIX.  To avoid this,
you should tell the compiler to produce rather inefficient but safe
code using the appropriate proclamation such as

    (proclaim '(optimize (safety 2))).

The safety level greater than or equal to 2 guarantees that the
code detects every runtime error.

2. KCL keeps several stacks.  Whenever an item is pushed on a
stack, KCL checks whether the stack limit is violated or not,
except for the value stack and the C stack.  The limit for the
value stack is not checked if the code was compiled with the
safety level 0; i.e., the limit is checked in the code compiled
with the safety level greater than 0, and in the interpreted code.

3. The limit for the C stack is not checked in the compiled code.

Note: KCL on BSD prepares the function SI:CATCH-BAD-SIGNALS which
installs the signal catcher for bad signals of UNIX:

    SIGILL, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS.

If you want to catch these signals, call SI:CATCH-BAD-SIGNALS with
no arguments.  When a signal is caught, KCL signals a Lisp error:

    Error: Signal 11 caught.

However, these signals mean that the internal memory of KCL may be
broken.  You should check the signal and exit from KCL if necessary.
When a signal is caught during garbage collection, KCL terminates
immedately.

SI:UNCATCH-BAD-SIGNALS will undo the effect.


* C Stack Limit

On BSD, you can specify the size of the C stack by the limit command
of csh.  KCL sets the C stack limit slightly smaller than the actual
stack size.  Therefore, for those applications that use much stack area,
one can invoke KCL in the following way:

    % limit stacksize 1024        # 1024K bytes = 1M bytes
    % kcl

Note: KCL will not extend the C stack size by itself.

Note: On SUN-3, the stack size is 512K bytes by default.

Note: When KCL detects the C stack overflow, it will signal a Lisp error
except in the garbage collector.  When the C stack overflows during
garbage collection, KCL terminates immediately.

Note: Big lists extending to the direction of car consume more stack
area than those extending to cdr during garbage collection.


* Process Size

Since KCL keeps a table which records the type of each page in the
process space, the process size of KCL is limited to the size of
the table.  Usually, the limit is set to 32M bytes on BSD, although it
can be easily changed by re-installing KCL.

On BSD, the size of the KCL process is further limited by the resource
limit set by the limit command of csh.  KCL does not change the limit by
itself.

Note: Even if the resource limit is large, you cannot use that much
because of the limitation of the swap space.  For example, on Sun-3,
you can hardly allocate 10M bytes in the standard installation.

Note: The process size KCL understands is held in the variable
SI:*LISP-MAXPAGES* in pages.


* Explicit Expansion of Process Space

Usually, KCL expands its process space dynamically.  In order to
allow the user to expand the process space of KCL immedately, the
function ALLOCATE and ALLOCATE-CONTIGUOUS-PAGES take one optional
argument.  When a non-NIL value is supplied for the optional argument,
these functions acutally allocate the maximum number of pages for the
specified implementation type or for the contiguous blocks.  Therefore,
you can begin with 1M bytes for conses (500 pages = 1M bytes) as follows:

    % kcl
    KCL (Kyoto Common Lisp) ...

    >(allocate 'cons 500 t)
    t

    >

Note: This facility is not specific to KCL/UNIX.


* Hole Size

The size of the hole between the heap and relocatable area (see Section
4.2 of the KCL Report) highly affects the performance of memory management.
With the smaller size of hole, garbage collection occurs more frequently,
but the total size of the (logical) memory used by KCL is kept smaller.
We prepare the following functions so that the user can set up the
"appropriate size" of his own.

(SI:GET-HOLE-SIZE) returns as an integer the hole size (in pages).
Note that this is NOT the size of the current hole, but IS the size
of the hole immediately after each garbage collection.

(SI:SET-HOLE-SIZE <fixnum>) sets the hole size.  <fixnum> is the
new size of the hole (in pages).  <fixnum> must be a positive fixnum.

To see how frequently the garbage collection occurs, set the variable
SI:*NOTIFY-GBC* to a non-NIL value.

Note: This feature is not specific to KCL/UNIX.


* Notification of garbage collection

When the value of the system-internal variable SI:*NOTIFY-GBC* is
non-NIL, the garbage collector will print

    GBC invoked

when it is invoked, and will print

    GBC finished

when it returns.

Note: The message is directly written on the standard output and is
not written on a Lisp stream.  Therefore, when one DRIBBLEs the KCL
session, the message from the garbage collector will not be written out
on the specified file.


* Big C Code

The C compiler sometimes complains that the code produced by KCL is too
big and cannot compute jump addresses.  To avoid this, you should supply
the assembler with the -J option as follows.

Compile the Lisp file by

    >(compile-file "foo.lsp" :c-file t :h-file t :data-file t
                   :o-file nil)

and compile the C file with the -S option

    % cc -S foo.c

and then assemble it with the -J option.

    % as -J foo.s -o foo.o

Finally, concatenate the data file at the end.

    % cat foo.data >> foo.o


* Faslink

The loader SI:FASLINK loads the object file while linking other object
files and/or libraries.  It is used as follows:

    (si:faslink "foo.o" "bar.o boo.o -lpixrect")

"foo.o" should be an object file produced by compiling a Lisp source file.
The Lisp file usually consists of DEFENTRY definitions that call
functions in the object files and/or the libraries specified in the
second argument.  The first argument should be a pathname, a string or a
symbol, and the second argument should be a string that can be accpted by
the UNIX linkage editor.  If there are more than one arguments, they
should be separated by a space as above.

Note: The second argument is passed to "ld" as it is.

Note: SI:FASLINK is only defined in the BSD versions of KCL.

Example:

test.lsp:

    (defentry c-shift (int int) (int c_shift))
    (defentry gamma (double) (double gamma))

shift.c:

    c_shift(x, y)
    int x, y;
    {
        return(x << y);
    }

Then,

    >(si:faslink "test" "shift.o -lm -lc")

will define C-SHIFT and GAMMA as intended.  Note that "test.lsp" should have
been compiled.


* Initial File

If there exists a file with the name "init.lsp" in the current directory,
KCL loads the file before entering into the top-level loop.  The user
of KCL is expected to make his/her own environment using this facility.
It is similar to ".chsrc" for csh, ".profile" for sh, or ".newsrc" for
readnews, although the name of the KCL initial file does not begin with ".".

For example, if you want to invoke your favorate editor from KCL, you can
define the interface in "init.lsp".

Example of init.lsp:

    (setq si:*ignore-eof-on-terminal-io* t)
    (setq si:*notify-gbc* t)
    (si:catch-bad-signals)
    (defun cd (file) (si:chdir file))
    (defun exit (&optional (code 0)) (bye code))
    (defvar *editor* (if (si:getenv "EDITOR") (si:getenv "EDITOR") "vi"))
    (defun ed (&optional (file "gazonk"))
      (system (format nil "~A ~A" *editor* (namestring file))))

Note: All the system-internal functions and variables that appear in the
above example are explained in this note.


* Ignoring EOF

The KCL top-level terminates when the standard input becomes end-of-file.
If you do not like this feature, assign a non-NIL value to the system-internal
variable SI:*IGNORE-EOF-ON-TERMINAL-IO*.  Then the stream *TERMINAL-IO* never
becomes end-of-file.


* Chdir

To change the current working directory of KCL, use the function
SI:CHDIR.

    (SI:CHDIR "../foo")

will change the current directory to "../foo".


* Environment

The environment of the KCL process is obtained by the function SI:GETENV.
SI:GETENV is the Lisp equivalent to the C library "getenv".
(SI:GETENV <string>) returns the value for the specified string in the
environment, or NIL, if the string is not found.


* Listen

LISTEN is implemented on BSD.  READ-CHAR-NO-HANG is also implemented,
but it does not follow the Common Lisp Manual completely.


* Summary of Useful System-interernal Functions and Variables

We extract useful system-internal functions and variables from the KCL
Dictionary.  These include all the functions and variables explained so far.

------------------------------------------------------------------------------
si:address                                                          [Function]

Args: (object)
KCL specific: Returns the address of the OBJECT as a fixnum.  The address of
an object depends on the version of KCL.  E.g. (SI:ADDRESS NIL) returns
1879062044 on KCL/AOSVS dated March 14, 1986.
------------------------------------------------------------------------------
si:argc                                                             [Function]

Args: ()
KCL specific: Returns the number of arguments on the command line that invoked
the KCL process.
------------------------------------------------------------------------------
si:argv                                                             [Function]

Args: (fixnum)
KCL specific: Returns the FIXNUM-th argument on the command line that invoked
the KCL process.
------------------------------------------------------------------------------
si:catch-bad-signals                                                [Function]

Args: ()
KCL/BSD specific: Installs a signal catcher for bad signals:
    SIGILL, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS.
The signal catcher, upon catching the signal, signals an error (and enter
the break-level).  Since the internal memory of KCL may be broken, the user
should check the signal and exit from KCL if necessary.  When the signal
is caught during garbage collection, KCL terminates immediately.
------------------------------------------------------------------------------
si:chdir                                                            [Function]

Args: (pathname)
KCL/UNIX specific: Changes the current working directory to the specified
pathname.
------------------------------------------------------------------------------
si:compiled-function-name                                           [Function]

Args: (compiled-function-object)
KCL specific: Returns the name of the COMPILED-FUNCTION-OBJECT.
------------------------------------------------------------------------------
si:copy-stream                                                      [Function]

Args: (in-stream out-stream)
KCL specific: Copies IN-STREAM to OUT-STREAM until the end-of-file on IN-
STREAM.
------------------------------------------------------------------------------

------------------------------------------------------------------------------
si:*default-time-zone*                                              [Variable]

KCL specific: Holds the default time zone.  The initial value of SI:*DEFAULT-
TIME-ZONE* is -9 (the time zone of Japan).
------------------------------------------------------------------------------
si:displaced-array-p                                                [Function]

Args (array)
KCL specific: Returns T if the ARRAY is a displaced array; NIL otherwise.
------------------------------------------------------------------------------
si:error-set                                                        [Function]

Args: (form)
KCL specific: Evaluates the FORM in the null environment.  If the evaluation
of the FORM has successfully completed, SI:ERROR-SET returns NIL as the first
value and the result of the evaluation as the rest of the values.  If, in the
course of the evaluation, a non-local jump from the FORM is atempted,
SI:ERROR-SET traps the jump and returns the corresponding jump tag as its
value.
------------------------------------------------------------------------------
si:faslink                                                          [Function]

Args: (file string)
KCL/BSD specific: Loads the FASL file FILE while linking the object files and
libraries specified by STRING.  For example,
    (faslink "foo.o" "bar.o boo.o -lpixrect")
loads foo.o while linking two object files (bar.o and boo.o) and the library
pixrect.  Usually, foo.o consists of the C language interface for the
functions defined in the object files or the libraries.
------------------------------------------------------------------------------
si:fixnump                                                          [Function]

Args: (object)
KCL specific: Returns T if the OBJECT is a fixnum; NIL otherwise.
------------------------------------------------------------------------------
si:get-string-input-stream-index                                    [Function]

Args: (string-input-stream)
KCL specific: Returns the current index of the STRING-INPUT-STREAM.
------------------------------------------------------------------------------
si:getenv                                                           [Function]

Args: (string)
KCL/UNIX specific: Returns the environment with the name STRING as a string;
if the environment specified by STRING is not found, returns NIL.
------------------------------------------------------------------------------
si:get-hole-size                                                    [Function]

Args: ()
KCL specific: Returns as a fixnum the size of the memory hole (in pages).
------------------------------------------------------------------------------

------------------------------------------------------------------------------
si:*ignore-eof-on-terminal-io*                                      [Variable]

KCL specific: If the value of SI:*IGNORE-EOF-ON-TERMINAL-IO* is non-NIL, KCL
ignores the eof-character (usually ^D) on the terminal and the terminal never
becomes end-of-file.  The default value of SI:*IGNORE-EOF-ON-TERMINAL-IO* is
NIL.
------------------------------------------------------------------------------
si:*indent-formatted-output*                                        [Variable]

KCL specific: The FORMAT directive ~% indents the next line if the value of
this variable is non-NIL.  If NIL, ~% simply does Newline.
------------------------------------------------------------------------------
si:init-system                                                      [Function]

Args: ()
KCL specific: Initializes the library and the compiler of KCL.  Since they
have already been initialized in the standard image of KCL, calling SI:INIT-
SYSTEM will cause an error.
------------------------------------------------------------------------------
si:*interrupt-enable*                                               [Variable]

KCL specific: If the value of SI:*INTERRUPT-ENABLE* is non-NIL, KCL signals
an error on the terminal interrupt (this is the default case).  If it is NIL,
KCL ignores the interrupt and assigns T to SI:*INTERRUPT-ENABLE*.
------------------------------------------------------------------------------
si:*lisp-maxpages*                                                  [Variable]

KCL specific: Holds the maximum number of pages (1 page = 2048 bytes) for the
KCL process.  The result of changing the value of SI:*LISP-MAXPAGES* is
unpredictable.
------------------------------------------------------------------------------
si:*make-constant                                                   [Function]

Args: (symbol value)
KCL specific: Makes the SYMBOL a constant with the specified VALUE.
------------------------------------------------------------------------------
si:*make-special                                                    [Function]

Args (symbol)
KCL specific: Makes the SYMBOL globally special.
------------------------------------------------------------------------------

------------------------------------------------------------------------------
si:make-string-output-stream-from-string                            [Function]

Args (string)
KCL specific: Creates a string-output-stream corresponding to the STRING and
returns it.  The STRING should have a fill-pointer.
------------------------------------------------------------------------------
si:nani                                                             [Function]

Args: (fixnum)
KCL specific: Returns the object in the address FIXNUM.  This function is
the inverse of SI:ADDRESS.  Although SI:ADDRESS is a harmless operation,
SI:NANI is quite dangerous and should be used with care.
------------------------------------------------------------------------------
si:*notify-gbc*                                                     [Variable]

KCL specific: If the value of this variable is non-NIL, then the garbage
collector notifies that it begins to run whenever it is invoked.  Otherwise,
garbage collection begins silently.
------------------------------------------------------------------------------
si:output-stream-string                                             [Function]

Args: (string-output-stream)
KCL specific: Returns the string corresponding to the STRING-OUTPUT-STREAM.
------------------------------------------------------------------------------
si:reset-gbc-count                                                  [Function]

Args: ()
KCL specific: Resets the counter of the garbage collector that records how
many times the garbage collector has been called for each implementation
type.
------------------------------------------------------------------------------
si:reset-stack-limits                                               [Function]

Args: ()
KCL specific: Resets the stack limits to the normal state.  When a stack has
overflowed, KCL extends the limit for the stack in order to execute the error
handler.  After processing the error, KCL resets the stack limit by calling
SI:RESET-STACK-LIMITS.
------------------------------------------------------------------------------
si:save-system                                                      [Function]

Args: (pathname)
KCL specific: Saves the current KCL core imange into a program file specified
by PATHNAME.  This function differs from SAVE in that the contiguous and
relocatable areas are made permanent in the saved image.  Usually the
standard image of KCL interpreter/compiler is saved by SI:SAVE-SYSTEM.
------------------------------------------------------------------------------
si:set-hole-size                                                    [Function]

Args: (fixnum)
KCL specific: Sets the size of the memory hole (in pages).
------------------------------------------------------------------------------
si:specialp                                                         [Function]

Args: (symbol)
KCL specific: Returns T if the SYMBOL is a globally special variable; NIL
otherwise.
------------------------------------------------------------------------------

------------------------------------------------------------------------------
si:string-concatenate                                               [Function]

Args: (&rest strings)
KCL specific: Returns the result of concatenating the given STRINGS.
------------------------------------------------------------------------------
si:string-to-object                                                 [Function]

Args: (string)
KCL specific: (SI:STRING-TO-OBJECT STRING) is equivalent to
(READ-FROM-STRING STRING), but much faster.
------------------------------------------------------------------------------
si:structurep                                                       [Function]

Args: (object)
KCL specific: Returns T if the OBJECT is a structure; NIL otherwise.
------------------------------------------------------------------------------
si:*system-directory*                                               [Variable]

KCL specific: Holds the name of the system directory of KCL.
------------------------------------------------------------------------------
si:top-level                                                        [Function]

Args: ()
KCL specific: Starts the standard top-level listner of KCL.  When the KCL
process is invoked, it calls SI:TOP-LEVEL by (FUNCALL 'SI:TOP-LEVEL).
     To change the top-level of KCL, redefine SI:TOP-LEVEL and save the core
imange in a file.  When the saved imange is invoked, it will start the
redefined top-level.
------------------------------------------------------------------------------
si:universal-error-handler                                          [Function]

Args: (error-name correctable function-name
       continue-format-string error-format-string
       &rest args)
KCL specific: Starts the error handler of KCL.  When an error is detected,
KCL calls SI:UNIVERSAL-ERROR-HANDLER with the specified arguments.
ERROR-NAME is the name of the error.  CORRECTABLE is T for a correctable
error and NIL for a fatal error.  FUNCTION-NAME is the name of the function
that caused the error.  CONTINUE-FORMAT-STRING and ERROR-FORMAT-STRING are
the format strings of the error message.  ARGS are the arguments to the
format strings.
     To change the error handler of KCL, redefine SI:UNIVERSAL-ERROR-
HANDLER.
------------------------------------------------------------------------------
si:uncatch-bad-signals                                              [Function]

Args: ()
KCL/BSD specific: Undoes the effect of SI:CATCH-BAD-SIGNALS.
------------------------------------------------------------------------------